Skip to content

Conversation

@banteg
Copy link

@banteg banteg commented Jan 14, 2026

Approach

This PR makes custom admonitions data‑driven and open‑ended in the UI while staying compatible with MiniJinja and existing theme semantics:

1) Consume arbitrary admonition types from config

  • Read config.extra.admonitions for icon/color definitions.
    • Supports both shorthand (todo = "lucide/list-todo") and mapping (todo = { icon = "…", color = "…" }).
  • Read config.theme.icon.admonition (opened up in core PR) for icon‑only overrides.
  • Collect all types across both sources and merge per type, preferring extra.admonitions.icon when present, otherwise falling back to theme.icon.admonition.

2) Generate CSS for any type (no closed set)

  • Emit CSS custom properties for each icon: --md-admonition-icon--<type> with inlined SVG data.
  • Emit per‑type rules for colors (background/border/title/icon) so a new type works with only config.
  • Use selectors that work for both regular and collapsible blocks: :is(.admonition, details).<type>.

3) Make templates MiniJinja‑safe

  • Replace list.append with namespace + list concatenation.
  • Replace dict.get with in checks and direct indexing.

4) Match theme variants

  • Modern: keep body tint + border (matches modern defaults).
  • Classic: apply only border + title tint (no body tint), matching classic defaults and avoiding the “double layer” look.

5) Keep dist artifacts in sync

  • Update both src/partials/icons.html and dist/partials/icons.html.

Files changed

  • src/partials/icons.html
  • dist/partials/icons.html

Behavior changes

  • Any extra.admonitions.<type> now produces a styled admonition with icon/color.
  • Any theme.icon.admonition.<type> now provides icon‑only customization.
  • Rendering no longer fails under MiniJinja.
  • Classic theme custom colors align with classic built‑ins (no body tint).

Cross‑repo context

Testing

  • Built a demo project with custom admonitions (modern + classic variants) and verified:
    • no template errors,
    • icons render for arbitrary types,
    • colors apply as configured,
    • classic visuals match built‑ins.

Scope notes

  • This PR does not add a config‑level title registry. Custom titles still use Markdown syntax (!!! type "Title").

Screenshot 2026-01-14 at 12 38 22 Screenshot 2026-01-14 at 12 39 57

@zensical
Copy link

zensical bot commented Jan 14, 2026

All commits verified and signed off.

Signed-off-by: banteg <4562643+banteg@users.noreply.github.com>
Signed-off-by: banteg <4562643+banteg@users.noreply.github.com>
Signed-off-by: banteg <4562643+banteg@users.noreply.github.com>
@squidfunk
Copy link
Member

Thanks for the PR! So, this is actually the scope of PR I thought your PR zensical/zensical#265 contains. It changes behavior fundamentally. Please see my rationale in zensical/zensical#265 (comment) why we need to turn this down right now. Since all changes are made in a template partial, you can just use template overrides to get the functionality proposed here.

Thanks for your understanding.

@squidfunk squidfunk closed this Jan 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants